46. 端点

执行器端点（endpoints）可用于监控应用及与应用进行交互，Spring Boot包含很多内置的端点，你也可以添加自己的。例如，health端点提供了应用的基本健康信息。 端点暴露的方式取决于你采用的技术类型，大部分应用选择HTTP监控，端点的ID映射到一个URL。例如，health端点默认映射到/health。

下面的端点都是可用的：

ID	描述	是否敏感
actuator	为其他端点提供基于超文本的导航页面，需要添加Spring HATEOAS依赖	true
autoconfig	显示一个自动配置类的报告，该报告展示所有自动配置候选者及它们被应用或未被应用的原因	true
beans	显示一个应用中所有Spring Beans的完整列表	true
configprops	显示一个所有@ConfigurationProperties的集合列表	true
dump	执行一个线程转储	true
env	暴露来自Spring ConfigurableEnvironment的属性	true
flyway	显示数据库迁移路径，如果有的话	true
health	展示应用的健康信息（当使用一个未认证连接访问时显示一个简单的'status'，使用认证连接访问则显示全部信息详情）	false
info	显示任意的应用信息	false
liquibase	展示任何Liquibase数据库迁移路径，如果有的话	true
metrics	展示当前应用的'metrics'信息	true
mappings	显示一个所有@RequestMapping路径的集合列表	true
shutdown	允许应用以优雅的方式关闭（默认情况下不启用）	true
trace	显示trace信息（默认为最新的100条HTTP请求）	true

如果使用Spring MVC，你还可以使用以下端点：

ID	描述	是否敏感
docs	展示Actuator的文档，包括示例请求和响应，需添加spring-boot-actuator-docs依赖	false
heapdump	返回一个GZip压缩的hprof堆转储文件	true
jolokia	通过HTTP暴露JMX beans（依赖Jolokia）	true
logfile	返回日志文件内容（如果设置logging.file或logging.path属性），支持使用HTTP Range头接收日志文件内容的部分信息

注：根据端点暴露的方式，sensitive属性可用做安全提示，例如，在使用HTTP访问敏感（sensitive）端点时需要提供用户名/密码（如果没有启用web安全，可能会简化为禁止访问该端点）。

46.1 自定义端点

使用Spring属性可以自定义端点，你可以设置端点是否开启（enabled），是否敏感（sensitive），甚至改变它的id。例如，下面的application.properties改变beans端点的敏感性及id，并启用shutdown：

endpoints.beans.id=springbeans
endpoints.beans.sensitive=false
endpoints.shutdown.enabled=true

注：前缀endpoints + . + name用于被配置端点的唯一标识。

默认情况，所有端点除了shutdown以外都是开启的，你可以使用endpoints.enabled属性指定可选端点是否启用。例如，所有端点除info外都被禁用：

endpoints.enabled=false
endpoints.info.enabled=true

同样地，你可以全局范围内设置所有端点的sensitive标记，敏感标记默认取决于端点类型（查看上面表格）。例如，所有端点除info外都标记为敏感：

endpoints.sensitive=true
endpoints.info.sensitive=false

46.2 执行器MVC端点的超媒体支持

如果classpath下存在Spring HATEOAS库（比如，通过spring-boot-starter-hateoas或使用Spring Data REST），来自执行器（Actuator）的HTTP端点将使用超媒体链接进行增强（hypermedia links），也就是使用一个“导航页”汇总所有端点链接，该页面默认路径为/actuator。该实现也是一个端点，可以通过属性配置它的路径（endpoints.actuator.path）及是否开启（endpoints.actuator.enabled）。

当指定了一个自定义管理上下文路径时，“导航页”路径自动从/actuator迁移到管理上下文根目录。例如，如果管理上下文路径为/management，那就可以通过/management访问“导航页”。

如果classpath下存在HAL Browser（通过webjar：org.webjars:hal-browser，或spring-data-rest-hal-browser），Spring Boot将提供一个以HAL Browser格式的HTML“导航页”。

46.4 添加自定义端点

如果添加一个Endpoint类型的@Bean，Spring Boot会自动通过JMX和HTTP（如果有可用服务器）将该端点暴露出去。通过创建MvcEndpoint类型的bean可进一步定义HTTP端点，虽然该bean不是@Controller，但仍能使用@RequestMapping（和@Managed*）暴露资源。

注 如果你的用户需要一个单独的管理端口或地址，你可以将注解@ManagementContextConfiguration的配置类添加到/META-INF/spring.factories中，且key为org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration，这样该端点将跟其他MVC端点一样移动到一个子上下文中，通过WebConfigurerAdapter可以为管理端点添加静态资源。

46.5 健康信息

健康信息可以检查应用的运行状态，它经常被监控软件用来提醒人们生产环境是否存在问题。health端点暴露的默认信息取决于端点是如何被访问的。对于一个非安全，未认证的连接只返回一个简单的'status'信息。对于一个安全或认证过的连接其他详细信息也会展示（具体参考章节47.7, “HTTP健康端点访问限制” ）。

健康信息是从你的ApplicationContext中定义的所有HealthIndicator beans收集过来的。Spring Boot包含很多自动配置的HealthIndicators，你也可以写自己的。

46.6 安全与HealthIndicators

HealthIndicators返回的信息通常有点敏感，例如，你可能不想将数据库服务器的详情发布到外面。因此，在使用一个未认证的HTTP连接时，默认只会暴露健康状态（health status）。如果想将所有的健康信息暴露出去，你可以把endpoints.health.sensitive设置为false。

为防止'拒绝服务'攻击，Health响应会被缓存，你可以使用endpoints.health.time-to-live属性改变默认的缓存时间（1000毫秒）。

46.6.1 自动配置的HealthIndicators

Spring Boot在合适的时候会自动配置以下HealthIndicators：

名称	描述
CassandraHealthIndicator	检查Cassandra数据库状况
DiskSpaceHealthIndicator	低磁盘空间检查
DataSourceHealthIndicator	检查是否能从DataSource获取连接
ElasticsearchHealthIndicator	检查Elasticsearch集群状况
JmsHealthIndicator	检查JMS消息代理状况
MailHealthIndicator	检查邮件服务器状况
MongoHealthIndicator	检查Mongo数据库状况
RabbitHealthIndicator	检查Rabbit服务器状况
RedisHealthIndicator	检查Redis服务器状况
SolrHealthIndicator	检查Solr服务器状况

注 使用management.health.defaults.enabled属性可以禁用以上全部HealthIndicators。

46.6.2 编写自定义HealthIndicators

你可以注册实现HealthIndicator接口的Spring beans来提供自定义健康信息。你需要实现health()方法，并返回一个Health响应，该响应需要包含一个status和其他用于展示的详情。

import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealth implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

}

注 对于给定HealthIndicator的标识是bean name去掉HealthIndicator后缀剩下的部分。在以上示例中，可以在my的实体中获取健康信息。

除Spring Boot预定义的Status类型，Health也可以返回一个代表新的系统状态的自定义Status。在这种情况下，你需要提供一个HealthAggregator接口的自定义实现，或使用management.health.status.order属性配置默认实现。

例如，假设一个新的，代码为FATAL的Status被用于你的一个HealthIndicator实现中。为了配置严重性级别，你需要将以下配置添加到application属性文件中：

management.health.status.order=DOWN, OUT_OF_SERVICE, UNKNOWN, UP

如果使用HTTP访问health端点，你可能想要注册自定义的status，并使用HealthMvcEndpoint进行映射。例如，你可以将FATAL映射为HttpStatus.SERVICE_UNAVAILABLE。

46.7 应用信息

应用信息会暴露所有InfoContributor beans收集的各种信息，Spring Boot包含很多自动配置的InfoContributors，你也可以编写自己的实现。

46.7.1 自动配置的InfoContributors

Spring Boot会在合适的时候自动配置以下InfoContributors：

名称	描述
EnvironmentInfoContributor	暴露Environment中key为info的所有key
GitInfoContributor	暴露git信息，如果存在git.properties文件
BuildInfoContributor	暴露构建信息，如果存在META-INF/build-info.properties文件

注 使用management.info.defaults.enabled属性可禁用以上所有InfoContributors。

46.7.2 自定义应用info信息

通过设置Spring属性info.*，你可以定义info端点暴露的数据。所有在info关键字下的Environment属性都将被自动暴露，例如，你可以将以下配置添加到application.properties：

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

注 你可以在构建时扩展info属性，而不是硬编码这些值。假设使用Maven，你可以按以下配置重写示例：

[email protected]@
[email protected]@
[email protected]@

46.7.3 Git提交信息

info端点的另一个有用特性是，在项目构建完成后发布git源码仓库的状态信息。如果GitProperties bean可用，Spring Boot将暴露git.branch，git.commit.id和git.commit.time属性。

注 如果classpath根目录存在git.properties文件，Spring Boot将自动配置GitProperties bean。查看Generate git information获取更多详细信息。

使用management.info.git.mode属性可展示全部git信息（比如git.properties全部内容）：

management.info.git.mode=full

46.7.4 构建信息

如果BuildProperties bean存在，info端点也会发布你的构建信息。

注 如果classpath下存在META-INF/build-info.properties文件，Spring Boot将自动构建BuildProperties bean。Maven和Gradle都能产生该文件，具体查看Generate build information。

46.7.5 编写自定义的InfoContributors

你可以注册实现了InfoContributor接口的Spring beans来提供自定义应用信息。以下示例暴露一个只有单个值的example实体：

import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class ExampleInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example",
                Collections.singletonMap("key", "value"));
    }

}

如果点击info端点，你应该可以看到包含以下实体的响应：

{
    "example": {
        "key" : "value"
    }
}